From 71fce930886cf194de14795a47ffca0d35ceda8d Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 1 Mar 2021 08:17:29 -0500 Subject: [PATCH] filechooserwidget: Convert docs --- gtk/gtkfilechooserwidget.c | 156 ++++++++++++++++++++----------------- 1 file changed, 86 insertions(+), 70 deletions(-) diff --git a/gtk/gtkfilechooserwidget.c b/gtk/gtkfilechooserwidget.c index 5674d3cbda..f6a58f3218 100644 --- a/gtk/gtkfilechooserwidget.c +++ b/gtk/gtkfilechooserwidget.c @@ -98,19 +98,17 @@ #endif /** - * SECTION:gtkfilechooserwidget - * @Short_description: A file chooser widget - * @Title: GtkFileChooserWidget - * @See_also: #GtkFileChooserDialog + * GtkFileChooserWidget: * - * #GtkFileChooserWidget is a widget for choosing files. - * It exposes the #GtkFileChooser interface, and you should + * `GtkFileChooserWidget` is a widget for choosing files. + * + * It exposes the [iface@Gtk.FileChooser] interface, and you should * use the methods of this interface to interact with the * widget. * * # CSS nodes * - * GtkFileChooserWidget has a single CSS node with name filechooser. + * `GtkFileChooserWidget` has a single CSS node with name filechooser. */ /* 150 mseconds of delay */ @@ -7265,17 +7263,19 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class) * @widget: the object which received the signal * @path: a string that gets put in the text entry for the file name * - * The ::location-popup signal is a [keybinding signal][GtkSignalAction] - * which gets emitted when the user asks for it. + * Emitted when the user asks for it. + * + * This is a [keybinding signal](class.SignalAction.html). * * This is used to make the file chooser show a "Location" prompt which * the user can use to manually type the name of the file he wishes to select. * - * The default bindings for this signal are `Control + L` with a @path string - * of "" (the empty string). It is also bound to `/` with a @path string of - * "`/`" (a slash): this lets you type `/` and immediately type a path name. - * On Unix systems, this is bound to `~` (tilde) with a @path string of "~" - * itself for access to home directories. + * The default bindings for this signal are Control-L + * with a @path string of "" (the empty string). It is also bound to + * / with a @path string of "`/`" (a slash): this lets you + * type `/` and immediately type a path name. On Unix systems, this is + * bound to ~ (tilde) with a @path string of "~" itself for + * access to home directories. */ signals[LOCATION_POPUP] = g_signal_new_class_handler (I_("location-popup"), @@ -7290,13 +7290,14 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class) * GtkFileChooserWidget::location-popup-on-paste: * @widget: the object which received the signal * - * The ::location-popup-on-paste signal is a [keybinding signal][GtkSignalAction] - * which gets emitted when the user asks for it. + * Emitted when the user asks for it. * - * This is used to make the file chooser show a "Location" prompt when the user - * pastes into a #GtkFileChooserWidget. + * This is a [keybinding signal](class.SignalAction.html). * - * The default binding for this signal is `Control + V`. + * This is used to make the file chooser show a "Location" prompt + * when the user pastes into a `GtkFileChooserWidget`. + * + * The default binding for this signal is Control-V. */ signals[LOCATION_POPUP_ON_PASTE] = g_signal_new_class_handler (I_("location-popup-on-paste"), @@ -7311,13 +7312,15 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class) * GtkFileChooserWidget::location-toggle-popup: * @widget: the object which received the signal * - * The ::location-toggle-popup signal is a [keybinding signal][GtkSignalAction] - * which gets emitted when the user asks for it. + * Emitted when the user asks for it. + * + * This is a [keybinding signal](class.SignalAction.html). * - * This is used to toggle the visibility of a "Location" prompt which the user - * can use to manually type the name of the file he wishes to select. + * This is used to toggle the visibility of a "Location" prompt + * which the user can use to manually type the name of the file + * he wishes to select. * - * The default binding for this signal is `Control + L`. + * The default binding for this signal is Control-L. */ signals[LOCATION_TOGGLE_POPUP] = g_signal_new_class_handler (I_("location-toggle-popup"), @@ -7332,13 +7335,14 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class) * GtkFileChooserWidget::up-folder: * @widget: the object which received the signal * - * The ::up-folder signal is a [keybinding signal][GtkSignalAction] - * which gets emitted when the user asks for it. + * Emitted when the user asks for it. * - * This is used to make the file chooser go to the parent of the current folder - * in the file hierarchy. + * This is a [keybinding signal](class.SignalAction.html). * - * The default binding for this signal is `Alt + Up`. + * This is used to make the file chooser go to the parent + * of the current folder in the file hierarchy. + * + * The default binding for this signal is Alt-Up. */ signals[UP_FOLDER] = g_signal_new_class_handler (I_("up-folder"), @@ -7353,16 +7357,18 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class) * GtkFileChooserWidget::down-folder: * @widget: the object which received the signal * - * The ::down-folder signal is a [keybinding signal][GtkSignalAction] - * which gets emitted when the user asks for it. + * Emitted when the user asks for it. + * + * This is a [keybinding signal](class.SignalAction.html). * - * This is used to make the file chooser go to a child of the current folder - * in the file hierarchy. The subfolder that will be used is displayed in the - * path bar widget of the file chooser. For example, if the path bar is showing - * "/foo/bar/baz", with bar currently displayed, then this will cause the file - * chooser to switch to the "baz" subfolder. + * This is used to make the file chooser go to a child of the + * current folder in the file hierarchy. The subfolder that will + * be used is displayed in the path bar widget of the file chooser. + * For example, if the path bar is showing "/foo/bar/baz", with bar + * currently displayed, then this will cause the file chooser to + * switch to the "baz" subfolder. * - * The default binding for this signal is `Alt + Down`. + * The default binding for this signal is Alt-Down. */ signals[DOWN_FOLDER] = g_signal_new_class_handler (I_("down-folder"), @@ -7377,13 +7383,14 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class) * GtkFileChooserWidget::home-folder: * @widget: the object which received the signal * - * The ::home-folder signal is a [keybinding signal][GtkSignalAction] - * which gets emitted when the user asks for it. + * Emitted when the user asks for it. + * + * This is a [keybinding signal](class.SignalAction.html). * * This is used to make the file chooser show the user's home * folder in the file list. * - * The default binding for this signal is `Alt + Home`. + * The default binding for this signal is Alt-Home. */ signals[HOME_FOLDER] = g_signal_new_class_handler (I_("home-folder"), @@ -7398,13 +7405,14 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class) * GtkFileChooserWidget::desktop-folder: * @widget: the object which received the signal * - * The ::desktop-folder signal is a [keybinding signal][GtkSignalAction] - * which gets emitted when the user asks for it. + * Emitted when the user asks for it. + * + * This is a [keybinding signal](class.SignalAction.html). * * This is used to make the file chooser show the user's Desktop * folder in the file list. * - * The default binding for this signal is `Alt + D`. + * The default binding for this signal is Alt-D. */ signals[DESKTOP_FOLDER] = g_signal_new_class_handler (I_("desktop-folder"), @@ -7420,18 +7428,20 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class) * @widget: the object which received the signal * @bookmark_index: the number of the bookmark to switch to * - * The ::quick-bookmark signal is a [keybinding signal][GtkSignalAction] - * which gets emitted when the user asks for it. + * Emitted when the user asks for it. * - * This is used to make the file chooser switch to the bookmark specified - * in the @bookmark_index parameter. For example, if you have three bookmarks, - * you can pass 0, 1, 2 to this signal to switch to each of them, respectively. + * This is a [keybinding signal](class.SignalAction.html). * - * The default binding for this signal is `Alt + 1`, `Alt + 2`, - * etc. until `Alt + 0`. Note that in the default binding, that - * `Alt + 1` is actually defined to switch to the bookmark at index - * 0, and so on successively; `Alt + 0` is defined to switch to the - * bookmark at index 10. + * This is used to make the file chooser switch to the bookmark + * specified in the @bookmark_index parameter. For example, if + * you have three bookmarks, you can pass 0, 1, 2 to this signal + * to switch to each of them, respectively. + * + * The default binding for this signal is Alt-1, + * Alt-2, etc. until Alt-0. + * Note that in the default binding, that Alt-1 is + * actually defined to switch to the bookmark at index 0, and so on + * successively. */ signals[QUICK_BOOKMARK] = g_signal_new_class_handler (I_("quick-bookmark"), @@ -7446,12 +7456,13 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class) * GtkFileChooserWidget::show-hidden: * @widget: the object which received the signal * - * The ::show-hidden signal is a [keybinding signal][GtkSignalAction] - * which gets emitted when the user asks for it. + * Emitted when the user asks for it. + * + * This is a [keybinding signal](class.SignalAction.html). * * This is used to make the file chooser display hidden files. * - * The default binding for this signal is `Control + H`. + * The default binding for this signal is Control-H. */ signals[SHOW_HIDDEN] = g_signal_new_class_handler (I_("show-hidden"), @@ -7466,12 +7477,13 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class) * GtkFileChooserWidget::search-shortcut: * @widget: the object which received the signal * - * The ::search-shortcut signal is a [keybinding signal][GtkSignalAction] - * which gets emitted when the user asks for it. + * Emitted when the user asks for it. + * + * This is a [keybinding signal](class.SignalAction.html). * * This is used to make the file chooser show the search entry. * - * The default binding for this signal is `Alt + S`. + * The default binding for this signal is Alt-S. */ signals[SEARCH_SHORTCUT] = g_signal_new_class_handler (I_("search-shortcut"), @@ -7486,12 +7498,13 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class) * GtkFileChooserWidget::recent-shortcut: * @widget: the object which received the signal * - * The ::recent-shortcut signal is a [keybinding signal][GtkSignalAction] - * which gets emitted when the user asks for it. + * Emitted when the user asks for it. + * + * This is a [keybinding signal](class.SignalAction.html). * * This is used to make the file chooser show the Recent location. * - * The default binding for this signal is `Alt + R`. + * The default binding for this signal is Alt-R. */ signals[RECENT_SHORTCUT] = g_signal_new_class_handler (I_("recent-shortcut"), @@ -7506,12 +7519,13 @@ gtk_file_chooser_widget_class_init (GtkFileChooserWidgetClass *class) * GtkFileChooserWidget::places-shortcut: * @widget: the object which received the signal * - * The ::places-shortcut signal is a [keybinding signal][GtkSignalAction] - * which gets emitted when the user asks for it. + * Emitted when the user asks for it. + * + * This is a [keybinding signal](class.SignalAction.html). * * This is used to move the focus to the places sidebar. * - * The default binding for this signal is `Alt + P`. + * The default binding for this signal is Alt-P. */ signals[PLACES_SHORTCUT] = g_signal_new_class_handler (I_("places-shortcut"), @@ -7892,12 +7906,14 @@ gtk_file_chooser_widget_init (GtkFileChooserWidget *impl) * gtk_file_chooser_widget_new: * @action: Open or save mode for the widget * - * Creates a new #GtkFileChooserWidget. This is a file chooser widget that can - * be embedded in custom windows, and it is the same widget that is used by - * #GtkFileChooserDialog. + * Creates a new `GtkFileChooserWidget`. + * + * This is a file chooser widget that can be embedded in custom + * windows, and it is the same widget that is used by + * `GtkFileChooserDialog`. * - * Returns: a new #GtkFileChooserWidget - **/ + * Returns: a new `GtkFileChooserWidget` + */ GtkWidget * gtk_file_chooser_widget_new (GtkFileChooserAction action) { -- 2.30.2